<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Threads</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GLib 参考手册">
<link rel="up" href="glib-core.html" title="GLib核心应用支持">
<link rel="prev" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop">
<link rel="next" href="glib-Thread-Pools.html" title="Thread Pools">
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="glib-The-Main-Event-Loop.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GLib 参考手册</th>
<td><a accesskey="n" href="glib-Thread-Pools.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#glib-Threads.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#glib-Threads.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry">
<a name="glib-Threads"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="glib-Threads.top_of_page"></a>Threads</span></h2>
<p>Threads — portable support for threads, mutexes, locks,
    conditions and thread private data</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="glib-Threads.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;glib.h&gt;

#define             <a class="link" href="glib-Threads.html#G-THREAD-ERROR:CAPS" title="G_THREAD_ERROR">G_THREAD_ERROR</a>
enum                <a class="link" href="glib-Threads.html#GThreadError" title="enum GThreadError">GThreadError</a>;

                    <a class="link" href="glib-Threads.html#GThread" title="GThread">GThread</a>;
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (<a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()">*GThreadFunc</a>)                      (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
<a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()">g_thread_new</a>                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *name</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
<a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-try-new" title="g_thread_try_new ()">g_thread_try_new</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *name</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
<a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-ref" title="g_thread_ref ()">g_thread_ref</a>                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> *thread</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-unref" title="g_thread_unref ()">g_thread_unref</a>                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> *thread</code></em>);
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()">g_thread_join</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> *thread</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-yield" title="g_thread_yield ()">g_thread_yield</a>                      ();
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()">g_thread_exit</a>                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> retval</code></em>);
<a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           <a class="link" href="glib-Threads.html#g-thread-self" title="g_thread_self ()">g_thread_self</a>                       (<em class="parameter"><code><span class="type">void</span></code></em>);

union               <a class="link" href="glib-Threads.html#GMutex" title="union GMutex">GMutex</a>;
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-init" title="g_mutex_init ()">g_mutex_init</a>                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-clear" title="g_mutex_clear ()">g_mutex_clear</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()">g_mutex_lock</a>                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()">g_mutex_trylock</a>                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()">g_mutex_unlock</a>                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);

#define             <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()">G_LOCK_DEFINE</a>                       (name)
#define             <a class="link" href="glib-Threads.html#G-LOCK-DEFINE-STATIC:CAPS" title="G_LOCK_DEFINE_STATIC()">G_LOCK_DEFINE_STATIC</a>                (name)
#define             <a class="link" href="glib-Threads.html#G-LOCK-EXTERN:CAPS" title="G_LOCK_EXTERN()">G_LOCK_EXTERN</a>                       (name)
#define             <a class="link" href="glib-Threads.html#G-LOCK:CAPS" title="G_LOCK()">G_LOCK</a>                              (name)
#define             <a class="link" href="glib-Threads.html#G-TRYLOCK:CAPS" title="G_TRYLOCK()">G_TRYLOCK</a>                           (name)
#define             <a class="link" href="glib-Threads.html#G-UNLOCK:CAPS" title="G_UNLOCK()">G_UNLOCK</a>                            (name)

struct              <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex">GRecMutex</a>;
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rec-mutex-init" title="g_rec_mutex_init ()">g_rec_mutex_init</a>                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rec-mutex-clear" title="g_rec_mutex_clear ()">g_rec_mutex_clear</a>                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rec-mutex-lock" title="g_rec_mutex_lock ()">g_rec_mutex_lock</a>                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-rec-mutex-trylock" title="g_rec_mutex_trylock ()">g_rec_mutex_trylock</a>                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rec-mutex-unlock" title="g_rec_mutex_unlock ()">g_rec_mutex_unlock</a>                  (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);

struct              <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock">GRWLock</a>;
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rw-lock-init" title="g_rw_lock_init ()">g_rw_lock_init</a>                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rw-lock-clear" title="g_rw_lock_clear ()">g_rw_lock_clear</a>                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rw-lock-writer-lock" title="g_rw_lock_writer_lock ()">g_rw_lock_writer_lock</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-rw-lock-writer-trylock" title="g_rw_lock_writer_trylock ()">g_rw_lock_writer_trylock</a>            (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rw-lock-writer-unlock" title="g_rw_lock_writer_unlock ()">g_rw_lock_writer_unlock</a>             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rw-lock-reader-lock" title="g_rw_lock_reader_lock ()">g_rw_lock_reader_lock</a>               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-rw-lock-reader-trylock" title="g_rw_lock_reader_trylock ()">g_rw_lock_reader_trylock</a>            (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-rw-lock-reader-unlock" title="g_rw_lock_reader_unlock ()">g_rw_lock_reader_unlock</a>             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);

struct              <a class="link" href="glib-Threads.html#GCond" title="struct GCond">GCond</a>;
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-init" title="g_cond_init ()">g_cond_init</a>                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-clear" title="g_cond_clear ()">g_cond_clear</a>                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()">g_cond_wait</a>                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-cond-timed-wait" title="g_cond_timed_wait ()">g_cond_timed_wait</a>                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *abs_time</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-cond-wait-until" title="g_cond_wait_until ()">g_cond_wait_until</a>                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="type">gint64</span></a> end_time</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-signal" title="g_cond_signal ()">g_cond_signal</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-cond-broadcast" title="g_cond_broadcast ()">g_cond_broadcast</a>                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);

struct              <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate">GPrivate</a>;
#define             <a class="link" href="glib-Threads.html#G-PRIVATE-INIT:CAPS" title="G_PRIVATE_INIT()">G_PRIVATE_INIT</a>                      (notify)
<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Threads.html#g-private-get" title="g_private_get ()">g_private_get</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> *key</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-private-set" title="g_private_set ()">g_private_set</a>                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> *key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-private-replace" title="g_private_replace ()">g_private_replace</a>                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> *key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);

struct              <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce">GOnce</a>;
enum                <a class="link" href="glib-Threads.html#GOnceStatus" title="enum GOnceStatus">GOnceStatus</a>;
#define             <a class="link" href="glib-Threads.html#G-ONCE-INIT:CAPS" title="G_ONCE_INIT">G_ONCE_INIT</a>
#define             <a class="link" href="glib-Threads.html#g-once" title="g_once()">g_once</a>                              (once,
                                                         func,
                                                         arg)
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()">g_once_init_enter</a>                   (<em class="parameter"><code>volatile <span class="type">void</span> *location</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-once-init-leave" title="g_once_init_leave ()">g_once_init_leave</a>                   (<em class="parameter"><code>volatile <span class="type">void</span> *location</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> result</code></em>);

<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-bit-lock" title="g_bit_lock ()">g_bit_lock</a>                          (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-bit-trylock" title="g_bit_trylock ()">g_bit_trylock</a>                       (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-bit-unlock" title="g_bit_unlock ()">g_bit_unlock</a>                        (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-pointer-bit-lock" title="g_pointer_bit_lock ()">g_pointer_bit_lock</a>                  (<em class="parameter"><code>volatile <span class="type">void</span> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Threads.html#g-pointer-bit-trylock" title="g_pointer_bit_trylock ()">g_pointer_bit_trylock</a>               (<em class="parameter"><code>volatile <span class="type">void</span> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
<span class="returnvalue">void</span>                <a class="link" href="glib-Threads.html#g-pointer-bit-unlock" title="g_pointer_bit_unlock ()">g_pointer_bit_unlock</a>                (<em class="parameter"><code>volatile <span class="type">void</span> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="glib-Threads.description"></a><h2>Description</h2>
<p>
Threads act almost like processes, but unlike processes all threads
of one process share the same memory. This is good, as it provides
easy communication between the involved threads via this shared
memory, and it is bad, because strange things (so called
"Heisenbugs") might happen if the program is not carefully designed.
In particular, due to the concurrent nature of threads, no
assumptions on the order of execution of code running in different
threads can be made, unless order is explicitly forced by the
programmer through synchronization primitives.
</p>
<p>
The aim of the thread-related functions in GLib is to provide a
portable means for writing multi-threaded software. There are
primitives for mutexes to protect the access to portions of memory
(<a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>, <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> and <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>). There is a facility to use
individual bits for locks (<a class="link" href="glib-Threads.html#g-bit-lock" title="g_bit_lock ()"><code class="function">g_bit_lock()</code></a>). There are primitives
for condition variables to allow synchronization of threads (<a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>).
There are primitives for thread-private data - data that every
thread has a private instance of (<a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a>). There are facilities
for one-time initialization (<a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>, <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a>). Finally,
there are primitives to create and manage threads (<a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>).
</p>
<p>
The GLib threading system used to be initialized with <a class="link" href="glib-Deprecated-Thread-APIs.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a>.
This is no longer necessary. Since version 2.32, the GLib threading
system is automatically initialized at the start of your program,
and all thread-creation functions and synchronization primitives
are available right away.
</p>
<p>
Note that it is not safe to assume that your program has no threads
even if you don't call <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a> yourself. GLib and GIO can
and will create threads for their own purposes in some cases, such
as when using <a class="link" href="glib-UNIX-specific-utilities-and-integration.html#g-unix-signal-source-new" title="g_unix_signal_source_new ()"><code class="function">g_unix_signal_source_new()</code></a> or when using GDBus.
</p>
<p>
Originally, UNIX did not have threads, and therefore some traditional
UNIX APIs are problematic in threaded programs. Some notable examples
are
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
    C library functions that return data in statically allocated
    buffers, such as <code class="function">strtok()</code> or <code class="function">strerror()</code>. For many of these,
    there are thread-safe variants with a _r suffix, or you can
    look at corresponding GLib APIs (like <a class="link" href="glib-String-Utility-Functions.html#g-strsplit" title="g_strsplit ()"><code class="function">g_strsplit()</code></a> or <a class="link" href="glib-String-Utility-Functions.html#g-strerror" title="g_strerror ()"><code class="function">g_strerror()</code></a>).
  </li>
<li class="listitem">
<code class="function">setenv()</code> and <code class="function">unsetenv()</code> manipulate the process environment in
    a not thread-safe way, and may interfere with <code class="function">getenv()</code> calls
    in other threads. Note that <code class="function">getenv()</code> calls may be
    <span class="quote">“<span class="quote">hidden</span>”</span> behind other APIs. For example, GNU <code class="function">gettext()</code>
    calls <code class="function">getenv()</code> under the covers. In general, it is best to treat
    the environment as readonly. If you absolutely have to modify the
    environment, do it early in <code class="function">main()</code>, when no other threads are around yet.
  </li>
<li class="listitem">
<a class="link" href="glib-running.html#setlocale" title="区域设置"><code class="function">setlocale()</code></a> changes the locale for the entire process, affecting
    all threads. Temporary changes to the locale are often made to
    change the behavior of string scanning or formatting functions
    like <code class="function">scanf()</code> or <code class="function">printf()</code>. GLib offers a number of string APIs
    (like <a class="link" href="glib-String-Utility-Functions.html#g-ascii-formatd" title="g_ascii_formatd ()"><code class="function">g_ascii_formatd()</code></a> or <a class="link" href="glib-String-Utility-Functions.html#g-ascii-strtod" title="g_ascii_strtod ()"><code class="function">g_ascii_strtod()</code></a>) that can often be
    used as an alternative. Or you can use the <code class="function">uselocale()</code> function
    to change the locale only for the current thread.
  </li>
<li class="listitem">
<code class="function">fork()</code> only takes the calling thread into the child's copy of the
    process image.  If other threads were executing in critical
    sections they could have left mutexes locked which could easily
    cause deadlocks in the new child.  For this reason, you should
    call <code class="function">exit()</code> or <code class="function">exec()</code> as soon as possible in the child and only
    make signal-safe library calls before that.
  </li>
<li class="listitem">
<code class="function">daemon()</code> uses <code class="function">fork()</code> in a way contrary to what is described
    above.  It should not be used with GLib programs.
  </li>
</ul></div>
<p>
</p>
<p>
GLib itself is internally completely thread-safe (all global data is
automatically locked), but individual data structure instances are
not automatically locked for performance reasons. For example,
you must coordinate accesses to the same <a class="link" href="glib-Hash-Tables.html#GHashTable" title="GHashTable"><span class="type">GHashTable</span></a> from multiple
threads. The two notable exceptions from this rule are <a class="link" href="glib-The-Main-Event-Loop.html#GMainLoop" title="GMainLoop"><span class="type">GMainLoop</span></a>
and <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>, which <span class="emphasis"><em>are</em></span> thread-safe and
need no further application-level locking to be accessed from
multiple threads. Most refcounting functions such as <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#g-object-ref"><code class="function">g_object_ref()</code></a>
are also thread-safe.
</p>
</div>
<div class="refsect1">
<a name="glib-Threads.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="G-THREAD-ERROR:CAPS"></a><h3>G_THREAD_ERROR</h3>
<pre class="programlisting">#define G_THREAD_ERROR g_thread_error_quark ()
</pre>
<p>
The error domain of the GLib thread subsystem.
</p>
</div>
<hr>
<div class="refsect2">
<a name="GThreadError"></a><h3>enum GThreadError</h3>
<pre class="programlisting">typedef enum {
  G_THREAD_ERROR_AGAIN /* Resource temporarily unavailable */
} GThreadError;
</pre>
<p>
Possible errors of thread related functions.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><a name="G-THREAD-ERROR-AGAIN:CAPS"></a><span class="term"><code class="literal">G_THREAD_ERROR_AGAIN</code></span></p></td>
<td>a thread couldn't be created due to resource
                       shortage. Try again later.
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GThread"></a><h3>GThread</h3>
<pre class="programlisting">typedef struct {
} GThread;
</pre>
<p>
The <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> struct represents a running thread. This struct
is returned by <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a> or <a class="link" href="glib-Threads.html#g-thread-try-new" title="g_thread_try_new ()"><code class="function">g_thread_try_new()</code></a>. You can
obtain the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> struct representing the current thead by
calling <a class="link" href="glib-Threads.html#g-thread-self" title="g_thread_self ()"><code class="function">g_thread_self()</code></a>.
</p>
<p>
GThread is refcounted, see <a class="link" href="glib-Threads.html#g-thread-ref" title="g_thread_ref ()"><code class="function">g_thread_ref()</code></a> and <a class="link" href="glib-Threads.html#g-thread-unref" title="g_thread_unref ()"><code class="function">g_thread_unref()</code></a>.
The thread represented by it holds a reference while it is running,
and <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> consumes the reference that it is given, so
it is normally not necessary to manage GThread references
explicitly.
</p>
<p>
The structure is opaque -- none of its fields may be directly
accessed.
</p>
</div>
<hr>
<div class="refsect2">
<a name="GThreadFunc"></a><h3>GThreadFunc ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (*GThreadFunc)                      (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
<p>
Specifies the type of the <em class="parameter"><code>func</code></em> functions passed to <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a>
or <a class="link" href="glib-Threads.html#g-thread-try-new" title="g_thread_try_new ()"><code class="function">g_thread_try_new()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>data passed to the thread</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the return value of the thread</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-new"></a><h3>g_thread_new ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           g_thread_new                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *name</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
<p>
This function creates a new thread. The new thread starts by invoking
<em class="parameter"><code>func</code></em> with the argument data. The thread will run until <em class="parameter"><code>func</code></em> returns
or until <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> is called from the new thread. The return value
of <em class="parameter"><code>func</code></em> becomes the return value of the thread, which can be obtained
with <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>.
</p>
<p>
The <em class="parameter"><code>name</code></em> can be useful for discriminating threads in a debugger.
Some systems restrict the length of <em class="parameter"><code>name</code></em> to 16 bytes.
</p>
<p>
If the thread can not be created the program aborts. See
<a class="link" href="glib-Threads.html#g-thread-try-new" title="g_thread_try_new ()"><code class="function">g_thread_try_new()</code></a> if you want to attempt to deal with failures.
</p>
<p>
To free the struct returned by this function, use <a class="link" href="glib-Threads.html#g-thread-unref" title="g_thread_unref ()"><code class="function">g_thread_unref()</code></a>.
Note that <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> implicitly unrefs the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> as well.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>a name for the new thread</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
<td>a function to execute in the new thread</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>an argument to supply to the new thread</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the new <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-try-new"></a><h3>g_thread_try_new ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           g_thread_try_new                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *name</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> func</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
<p>
This function is the same as <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a> except that
it allows for the possibility of failure.
</p>
<p>
If a thread can not be created (due to resource limits),
<em class="parameter"><code>error</code></em> is set and <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>a name for the new thread</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
<td>a function to execute in the new thread</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>an argument to supply to the new thread</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
<td>return location for error, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the new <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> if an error occurred</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-ref"></a><h3>g_thread_ref ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           g_thread_ref                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> *thread</code></em>);</pre>
<p>
Increase the reference count on <em class="parameter"><code>thread</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new reference to <em class="parameter"><code>thread</code></em>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-unref"></a><h3>g_thread_unref ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_unref                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> *thread</code></em>);</pre>
<p>
Decrease the reference count on <em class="parameter"><code>thread</code></em>, possibly freeing all
resources associated with it.
</p>
<p>
Note that each thread holds a reference to its <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> while
it is running, so it is safe to drop your own reference to it
if you don't need it anymore.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-join"></a><h3>g_thread_join ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_thread_join                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> *thread</code></em>);</pre>
<p>
Waits until <em class="parameter"><code>thread</code></em> finishes, i.e. the function <em class="parameter"><code>func</code></em>, as
given to <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a>, returns or <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> is called.
If <em class="parameter"><code>thread</code></em> has already terminated, then <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>
returns immediately.
</p>
<p>
Any thread can wait for any other thread by calling <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>,
not just its 'creator'. Calling <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> from multiple threads
for the same <em class="parameter"><code>thread</code></em> leads to undefined behaviour.
</p>
<p>
The value returned by <em class="parameter"><code>func</code></em> or given to <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> is
returned by this function.
</p>
<p>
<a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> consumes the reference to the passed-in <em class="parameter"><code>thread</code></em>.
This will usually cause the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> struct and associated resources
to be freed. Use <a class="link" href="glib-Threads.html#g-thread-ref" title="g_thread_ref ()"><code class="function">g_thread_ref()</code></a> to obtain an extra reference if you
want to keep the GThread alive beyond the <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> call.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>thread</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the return value of the thread</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-yield"></a><h3>g_thread_yield ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_yield                      ();</pre>
<p>
Causes the calling thread to voluntarily relinquish the CPU, so
that other threads can run.
</p>
<p>
This function is often used as a method to make busy wait less evil.
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-exit"></a><h3>g_thread_exit ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_thread_exit                       (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> retval</code></em>);</pre>
<p>
Terminates the current thread.
</p>
<p>
If another thread is waiting for us using <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a> then the
waiting thread will be woken up and get <em class="parameter"><code>retval</code></em> as the return value
of <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>.
</p>
<p>
Calling <code class="literal">g_thread_exit (retval)</code> is equivalent to
returning <em class="parameter"><code>retval</code></em> from the function <em class="parameter"><code>func</code></em>, as given to <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
  You must only call <a class="link" href="glib-Threads.html#g-thread-exit" title="g_thread_exit ()"><code class="function">g_thread_exit()</code></a> from a thread that you created
  yourself with <a class="link" href="glib-Threads.html#g-thread-new" title="g_thread_new ()"><code class="function">g_thread_new()</code></a> or related APIs.  You must not call
  this function from a thread created with another threading library
  or or from within a <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>.
</p>
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>retval</code></em> :</span></p></td>
<td>the return value of this thread</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-thread-self"></a><h3>g_thread_self ()</h3>
<pre class="programlisting"><a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="returnvalue">GThread</span></a> *           g_thread_self                       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
<p>
This functions returns the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.
</p>
<p>
This function will return a <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> even for threads that
were not created by GLib (i.e. those created by other threading
APIs). This may be useful for thread identification purposes
(i.e. comparisons) but you must not use GLib functions (such
as <a class="link" href="glib-Threads.html#g-thread-join" title="g_thread_join ()"><code class="function">g_thread_join()</code></a>) on these threads.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the <a class="link" href="glib-Threads.html#GThread" title="GThread"><span class="type">GThread</span></a> representing the current thread</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GMutex"></a><h3>union GMutex</h3>
<pre class="programlisting">union _GMutex
{
  /*&lt; private &gt;*/
  gpointer p;
  guint i[2];
};
</pre>
<p>
The <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> struct is an opaque data structure to represent a mutex
(mutual exclusion). It can be used to protect data against shared
access. Take for example the following function:
</p>
<p>
</p>
<div class="example">
<a name="idp7538760"></a><p class="title"><b>Example 2. A function which will not work in a threaded environment</b></p>
<div class="example-contents"><pre class="programlisting">
  int
  give_me_next_number (void)
  {
    static int current_number = 0;

    /* now do a very complicated calculation to calculate the new
     * number, this might for example be a random number generator
     */
    current_number = calc_next_number (current_number);

    return current_number;
  }
 </pre></div>
</div>
<p><br class="example-break">
</p>
<p>
It is easy to see that this won't work in a multi-threaded
application. There current_number must be protected against shared
access. A <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> can be used as a solution to this problem:
</p>
<p>
</p>
<div class="example">
<a name="idp7541320"></a><p class="title"><b>Example 3. Using GMutex to protected a shared variable</b></p>
<div class="example-contents"><pre class="programlisting">
  int
  give_me_next_number (void)
  {
    static GMutex mutex;
    static int current_number = 0;
    int ret_val;

    g_mutex_lock (&amp;mutex);
    ret_val = current_number = calc_next_number (current_number);
    g_mutex_unlock (&amp;mutex);

    return ret_val;
  }
 </pre></div>
</div>
<p><br class="example-break">
</p>
<p>
Notice that the <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> is not initialised to any particular value.
Its placement in static storage ensures that it will be initialised
to all-zeros, which is appropriate.
</p>
<p>
If a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> is placed in other contexts (eg: embedded in a struct)
then it must be explicitly initialised using <a class="link" href="glib-Threads.html#g-mutex-init" title="g_mutex_init ()"><code class="function">g_mutex_init()</code></a>.
</p>
<p>
A <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> should only be accessed via <code class="function">g_mutex_</code>
functions.
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-init"></a><h3>g_mutex_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_init                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Initializes a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> so that it can be used.
</p>
<p>
This function is useful to initialize a mutex that has been
allocated on the stack, or as part of a larger structure.
It is not necessary to initialize a mutex that has been
created that has been statically allocated.
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
  typedef struct {
    GMutex m;
    ...
  } Blob;

Blob *b;

b = g_new (Blob, 1);
g_mutex_init (&amp;b-&gt;m);
</pre></div>
<p>
</p>
<p>
To undo the effect of <a class="link" href="glib-Threads.html#g-mutex-init" title="g_mutex_init ()"><code class="function">g_mutex_init()</code></a> when a mutex is no longer
needed, use <a class="link" href="glib-Threads.html#g-mutex-clear" title="g_mutex_clear ()"><code class="function">g_mutex_clear()</code></a>.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-mutex-init" title="g_mutex_init ()"><code class="function">g_mutex_init()</code></a> on an already initialized <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> leads
to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>an uninitialized <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-clear"></a><h3>g_mutex_clear ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_clear                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Frees the resources allocated to a mutex with <a class="link" href="glib-Threads.html#g-mutex-init" title="g_mutex_init ()"><code class="function">g_mutex_init()</code></a>.
</p>
<p>
This function should not be used with a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> that has been
statically allocated.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-mutex-clear" title="g_mutex_clear ()"><code class="function">g_mutex_clear()</code></a> on a locked mutex leads to undefined
behaviour.
</p>
<p>
Sine: 2.32
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>an initialized <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-lock"></a><h3>g_mutex_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_lock                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Locks <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread, the
current thread will block until <em class="parameter"><code>mutex</code></em> is unlocked by the other
thread.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> is neither guaranteed to be recursive nor to be
non-recursive.  As such, calling <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a> on a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks).</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-trylock"></a><h3>g_mutex_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_mutex_trylock                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Tries to lock <em class="parameter"><code>mutex</code></em>. If <em class="parameter"><code>mutex</code></em> is already locked by another thread,
it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise it locks <em class="parameter"><code>mutex</code></em> and returns
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> is neither guaranteed to be recursive nor to be
non-recursive.  As such, calling <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a> on a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks or arbitrary return values).
</div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>mutex</code></em> could be locked</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-mutex-unlock"></a><h3>g_mutex_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_mutex_unlock                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Unlocks <em class="parameter"><code>mutex</code></em>. If another thread is blocked in a <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>
call for <em class="parameter"><code>mutex</code></em>, it will become unblocked and can lock <em class="parameter"><code>mutex</code></em> itself.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a> on a mutex that is not locked by the
current thread leads to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK-DEFINE:CAPS"></a><h3>G_LOCK_DEFINE()</h3>
<pre class="programlisting">#define G_LOCK_DEFINE(name)    
</pre>
<p>
The <code class="literal">G_LOCK_*</code> macros provide a convenient interface to <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>.
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a> defines a lock. It can appear in any place where
variable definitions may appear in programs, i.e. in the first block
of a function or outside of functions. The <em class="parameter"><code>name</code></em> parameter will be
mangled to get the name of the <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a>. This means that you
can use names of existing variables as the parameter - e.g. the name
of the variable you intend to protect with the lock. Look at our
<code class="function"><code class="function">give_me_next_number()</code></code> example using the
<code class="literal">G_LOCK_*</code> macros:
</p>
<p>
</p>
<div class="example">
<a name="idp7595440"></a><p class="title"><b>Example 4. Using the <code class="literal">G_LOCK_*</code> convenience macros</b></p>
<div class="example-contents"><pre class="programlisting">
  G_LOCK_DEFINE (current_number);

  int
  give_me_next_number (void)
  {
    static int current_number = 0;
    int ret_val;

    G_LOCK (current_number);
    ret_val = current_number = calc_next_number (current_number);
    G_UNLOCK (current_number);

    return ret_val;
  }
 </pre></div>
</div>
<p><br class="example-break">
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK-DEFINE-STATIC:CAPS"></a><h3>G_LOCK_DEFINE_STATIC()</h3>
<pre class="programlisting">#define G_LOCK_DEFINE_STATIC(name)
</pre>
<p>
This works like <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>, but it creates a static object.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK-EXTERN:CAPS"></a><h3>G_LOCK_EXTERN()</h3>
<pre class="programlisting">#define G_LOCK_EXTERN(name)    
</pre>
<p>
This declares a lock, that is defined with <a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a> in another
module.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-LOCK:CAPS"></a><h3>G_LOCK()</h3>
<pre class="programlisting">#define G_LOCK(name)
</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-lock" title="g_mutex_lock ()"><code class="function">g_mutex_lock()</code></a>, but for a lock defined with
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-TRYLOCK:CAPS"></a><h3>G_TRYLOCK()</h3>
<pre class="programlisting">#define G_TRYLOCK(name)
</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-trylock" title="g_mutex_trylock ()"><code class="function">g_mutex_trylock()</code></a>, but for a lock defined with
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>, if the lock could be locked.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="G-UNLOCK:CAPS"></a><h3>G_UNLOCK()</h3>
<pre class="programlisting">#define G_UNLOCK(name)
</pre>
<p>
Works like <a class="link" href="glib-Threads.html#g-mutex-unlock" title="g_mutex_unlock ()"><code class="function">g_mutex_unlock()</code></a>, but for a lock defined with
<a class="link" href="glib-Threads.html#G-LOCK-DEFINE:CAPS" title="G_LOCK_DEFINE()"><span class="type">G_LOCK_DEFINE</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em> :</span></p></td>
<td>the name of the lock</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GRecMutex"></a><h3>struct GRecMutex</h3>
<pre class="programlisting">struct GRecMutex {
};
</pre>
<p>
The GRecMutex struct is an opaque data structure to represent a
recursive mutex. It is similar to a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> with the difference
that it is possible to lock a GRecMutex multiple times in the same
thread without deadlock. When doing so, care has to be taken to
unlock the recursive mutex as often as it has been locked.
</p>
<p>
If a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> is allocated in static storage then it can be used
without initialisation.  Otherwise, you should call
<a class="link" href="glib-Threads.html#g-rec-mutex-init" title="g_rec_mutex_init ()"><code class="function">g_rec_mutex_init()</code></a> on it and <a class="link" href="glib-Threads.html#g-rec-mutex-clear" title="g_rec_mutex_clear ()"><code class="function">g_rec_mutex_clear()</code></a> when done.
</p>
<p>
A GRecMutex should only be accessed with the
<code class="function">g_rec_mutex_</code> functions.
</p>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rec-mutex-init"></a><h3>g_rec_mutex_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rec_mutex_init                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);</pre>
<p>
Initializes a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> so that it can be used.
</p>
<p>
This function is useful to initialize a recursive mutex
that has been allocated on the stack, or as part of a larger
structure.
</p>
<p>
It is not necessary to initialise a recursive mutex that has been
statically allocated.
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
  typedef struct {
    GRecMutex m;
    ...
  } Blob;

Blob *b;

b = g_new (Blob, 1);
g_rec_mutex_init (&amp;b-&gt;m);
</pre></div>
<p>
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rec-mutex-init" title="g_rec_mutex_init ()"><code class="function">g_rec_mutex_init()</code></a> on an already initialized <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
leads to undefined behaviour.
</p>
<p>
To undo the effect of <a class="link" href="glib-Threads.html#g-rec-mutex-init" title="g_rec_mutex_init ()"><code class="function">g_rec_mutex_init()</code></a> when a recursive mutex
is no longer needed, use <a class="link" href="glib-Threads.html#g-rec-mutex-clear" title="g_rec_mutex_clear ()"><code class="function">g_rec_mutex_clear()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
<td>an uninitialized <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rec-mutex-clear"></a><h3>g_rec_mutex_clear ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rec_mutex_clear                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);</pre>
<p>
Frees the resources allocated to a recursive mutex with
<a class="link" href="glib-Threads.html#g-rec-mutex-init" title="g_rec_mutex_init ()"><code class="function">g_rec_mutex_init()</code></a>.
</p>
<p>
This function should not be used with a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> that has been
statically allocated.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rec-mutex-clear" title="g_rec_mutex_clear ()"><code class="function">g_rec_mutex_clear()</code></a> on a locked recursive mutex leads
to undefined behaviour.
</p>
<p>
Sine: 2.32
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
<td>an initialized <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-rec-mutex-lock"></a><h3>g_rec_mutex_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rec_mutex_lock                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);</pre>
<p>
Locks <em class="parameter"><code>rec_mutex</code></em>. If <em class="parameter"><code>rec_mutex</code></em> is already locked by another
thread, the current thread will block until <em class="parameter"><code>rec_mutex</code></em> is
unlocked by the other thread. If <em class="parameter"><code>rec_mutex</code></em> is already locked
by the current thread, the 'lock count' of <em class="parameter"><code>rec_mutex</code></em> is increased.
The mutex will only become available again when it is unlocked
as many times as it has been locked.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rec-mutex-trylock"></a><h3>g_rec_mutex_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_rec_mutex_trylock                 (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);</pre>
<p>
Tries to lock <em class="parameter"><code>rec_mutex</code></em>. If <em class="parameter"><code>rec_mutex</code></em> is already locked
by another thread, it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>. Otherwise
it locks <em class="parameter"><code>rec_mutex</code></em> and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>rec_mutex</code></em> could be locked</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rec-mutex-unlock"></a><h3>g_rec_mutex_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rec_mutex_unlock                  (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a> *rec_mutex</code></em>);</pre>
<p>
Unlocks <em class="parameter"><code>rec_mutex</code></em>. If another thread is blocked in a
<a class="link" href="glib-Threads.html#g-rec-mutex-lock" title="g_rec_mutex_lock ()"><code class="function">g_rec_mutex_lock()</code></a> call for <em class="parameter"><code>rec_mutex</code></em>, it will become unblocked
and can lock <em class="parameter"><code>rec_mutex</code></em> itself.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rec-mutex-unlock" title="g_rec_mutex_unlock ()"><code class="function">g_rec_mutex_unlock()</code></a> on a recursive mutex that is not
locked by the current thread leads to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rec_mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRecMutex" title="struct GRecMutex"><span class="type">GRecMutex</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="GRWLock"></a><h3>struct GRWLock</h3>
<pre class="programlisting">struct GRWLock {
};
</pre>
<p>
The GRWLock struct is an opaque data structure to represent a
reader-writer lock. It is similar to a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> in that it allows
multiple threads to coordinate access to a shared resource.
</p>
<p>
The difference to a mutex is that a reader-writer lock discriminates
between read-only ('reader') and full ('writer') access. While only
one thread at a time is allowed write access (by holding the 'writer'
lock via <a class="link" href="glib-Threads.html#g-rw-lock-writer-lock" title="g_rw_lock_writer_lock ()"><code class="function">g_rw_lock_writer_lock()</code></a>), multiple threads can gain
simultaneous read-only access (by holding the 'reader' lock via
<a class="link" href="glib-Threads.html#g-rw-lock-reader-lock" title="g_rw_lock_reader_lock ()"><code class="function">g_rw_lock_reader_lock()</code></a>).
</p>
<p>
</p>
<div class="example">
<a name="idp7673072"></a><p class="title"><b>Example 5. An array with access functions</b></p>
<div class="example-contents">
<pre class="programlisting">
  GRWLock lock;
  GPtrArray *array;

  gpointer
  my_array_get (guint index)
  {
    gpointer retval = NULL;

    if (!array)
      return NULL;

    g_rw_lock_reader_lock (&amp;lock);
    if (index &lt; array-&gt;len)
      retval = g_ptr_array_index (array, index);
    g_rw_lock_reader_unlock (&amp;lock);

    return retval;
  }

  void
  my_array_set (guint index, gpointer data)
  {
    g_rw_lock_writer_lock (&amp;lock);

    if (!array)
      array = g_ptr_array_new ();

    if (index &gt;= array-&gt;len)
      g_ptr_array_set_size (array, index+1);
    g_ptr_array_index (array, index) = data;

    g_rw_lock_writer_unlock (&amp;lock);
  }
 </pre>
<p>
   This example shows an array which can be accessed by many readers
   (the <code class="function"><code class="function">my_array_get()</code></code> function) simultaneously,
   whereas the writers (the <code class="function"><code class="function">my_array_set()</code></code>
   function) will only be allowed once at a time and only if no readers
   currently access the array. This is because of the potentially
   dangerous resizing of the array. Using these functions is fully
   multi-thread safe now.
 </p>
</div>
</div>
<p><br class="example-break">
</p>
<p>
If a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> is allocated in static storage then it can be used
without initialisation.  Otherwise, you should call
<a class="link" href="glib-Threads.html#g-rw-lock-init" title="g_rw_lock_init ()"><code class="function">g_rw_lock_init()</code></a> on it and <a class="link" href="glib-Threads.html#g-rw-lock-clear" title="g_rw_lock_clear ()"><code class="function">g_rw_lock_clear()</code></a> when done.
</p>
<p>
A GRWLock should only be accessed with the
<code class="function">g_rw_lock_</code> functions.
</p>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-init"></a><h3>g_rw_lock_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rw_lock_init                      (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Initializes a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> so that it can be used.
</p>
<p>
This function is useful to initialize a lock that has been
allocated on the stack, or as part of a larger structure.  It is not
necessary to initialise a reader-writer lock that has been statically
allocated.
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
  typedef struct {
    GRWLock l;
    ...
  } Blob;

Blob *b;

b = g_new (Blob, 1);
g_rw_lock_init (&amp;b-&gt;l);
</pre></div>
<p>
</p>
<p>
To undo the effect of <a class="link" href="glib-Threads.html#g-rw-lock-init" title="g_rw_lock_init ()"><code class="function">g_rw_lock_init()</code></a> when a lock is no longer
needed, use <a class="link" href="glib-Threads.html#g-rw-lock-clear" title="g_rw_lock_clear ()"><code class="function">g_rw_lock_clear()</code></a>.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rw-lock-init" title="g_rw_lock_init ()"><code class="function">g_rw_lock_init()</code></a> on an already initialized <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> leads
to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>an uninitialized <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-clear"></a><h3>g_rw_lock_clear ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rw_lock_clear                     (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Frees the resources allocated to a lock with <a class="link" href="glib-Threads.html#g-rw-lock-init" title="g_rw_lock_init ()"><code class="function">g_rw_lock_init()</code></a>.
</p>
<p>
This function should not be used with a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> that has been
statically allocated.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rw-lock-clear" title="g_rw_lock_clear ()"><code class="function">g_rw_lock_clear()</code></a> when any thread holds the lock
leads to undefined behaviour.
</p>
<p>
Sine: 2.32
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>an initialized <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-writer-lock"></a><h3>g_rw_lock_writer_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rw_lock_writer_lock               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Obtain a write lock on <em class="parameter"><code>rw_lock</code></em>. If any thread already holds
a read or write lock on <em class="parameter"><code>rw_lock</code></em>, the current thread will block
until all other threads have dropped their locks on <em class="parameter"><code>rw_lock</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-writer-trylock"></a><h3>g_rw_lock_writer_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_rw_lock_writer_trylock            (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Tries to obtain a write lock on <em class="parameter"><code>rw_lock</code></em>. If any other thread holds
a read or write lock on <em class="parameter"><code>rw_lock</code></em>, it immediately returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>.
Otherwise it locks <em class="parameter"><code>rw_lock</code></em> and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>rw_lock</code></em> could be locked</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-writer-unlock"></a><h3>g_rw_lock_writer_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rw_lock_writer_unlock             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Release a write lock on <em class="parameter"><code>rw_lock</code></em>.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rw-lock-writer-unlock" title="g_rw_lock_writer_unlock ()"><code class="function">g_rw_lock_writer_unlock()</code></a> on a lock that is not held
by the current thread leads to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-reader-lock"></a><h3>g_rw_lock_reader_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rw_lock_reader_lock               (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Obtain a read lock on <em class="parameter"><code>rw_lock</code></em>. If another thread currently holds
the write lock on <em class="parameter"><code>rw_lock</code></em> or blocks waiting for it, the current
thread will block. Read locks can be taken recursively.
</p>
<p>
It is implementation-defined how many threads are allowed to
hold read locks on the same lock simultaneously.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-reader-trylock"></a><h3>g_rw_lock_reader_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_rw_lock_reader_trylock            (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Tries to obtain a read lock on <em class="parameter"><code>rw_lock</code></em> and returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if
the read lock was successfully obtained. Otherwise it
returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>rw_lock</code></em> could be locked</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-rw-lock-reader-unlock"></a><h3>g_rw_lock_reader_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_rw_lock_reader_unlock             (<em class="parameter"><code><a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a> *rw_lock</code></em>);</pre>
<p>
Release a read lock on <em class="parameter"><code>rw_lock</code></em>.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-rw-lock-reader-unlock" title="g_rw_lock_reader_unlock ()"><code class="function">g_rw_lock_reader_unlock()</code></a> on a lock that is not held
by the current thread leads to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>rw_lock</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GRWLock" title="struct GRWLock"><span class="type">GRWLock</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="GCond"></a><h3>struct GCond</h3>
<pre class="programlisting">struct GCond {
};
</pre>
<p>
The <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> struct is an opaque data structure that represents a
condition. Threads can block on a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> if they find a certain
condition to be false. If other threads change the state of this
condition they signal the <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>, and that causes the waiting
threads to be woken up.
</p>
<p>
Consider the following example of a shared variable.  One or more
threads can wait for data to be published to the variable and when
another thread publishes the data, it can signal one of the waiting
threads to wake up to collect the data.
</p>
<p>
</p>
<div class="example">
<a name="idp7745200"></a><p class="title"><b>Example 6. 
  Using GCond to block a thread until a condition is satisfied
 </b></p>
<div class="example-contents"><pre class="programlisting">
  gpointer current_data = NULL;
  GMutex data_mutex;
  GCond data_cond;

  void
  push_data (gpointer data)
  {
    g_mutex_lock (&amp;data_mutex);
    current_data = data;
    g_cond_signal (&amp;data_cond);
    g_mutex_unlock (&amp;data_mutex);
  }

  gpointer
  pop_data (void)
  {
    gpointer data;

    g_mutex_lock (&amp;data_mutex);
    while (!current_data)
      g_cond_wait (&amp;data_cond, &amp;data_mutex);
    data = current_data;
    current_data = NULL;
    g_mutex_unlock (&amp;data_mutex);

    return data;
  }
 </pre></div>
</div>
<p><br class="example-break">
</p>
<p>
Whenever a thread calls <code class="function">pop_data()</code> now, it will wait until
current_data is non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, i.e. until some other thread
has called <code class="function">push_data()</code>.
</p>
<p>
The example shows that use of a condition variable must always be
paired with a mutex.  Without the use of a mutex, there would be a
race between the check of <code class="varname">current_data</code> by the
while loop in <code class="function">pop_data</code> and waiting.
Specifically, another thread could set <code class="varname">pop_data</code>
after the check, and signal the cond (with nobody waiting on it)
before the first thread goes to sleep.  <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> is specifically useful
for its ability to release the mutex and go to sleep atomically.
</p>
<p>
It is also important to use the <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> and <a class="link" href="glib-Threads.html#g-cond-wait-until" title="g_cond_wait_until ()"><code class="function">g_cond_wait_until()</code></a>
functions only inside a loop which checks for the condition to be
true.  See <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> for an explanation of why the condition may
not be true even after it returns.
</p>
<p>
If a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> is allocated in static storage then it can be used
without initialisation.  Otherwise, you should call <a class="link" href="glib-Threads.html#g-cond-init" title="g_cond_init ()"><code class="function">g_cond_init()</code></a> on
it and <a class="link" href="glib-Threads.html#g-cond-clear" title="g_cond_clear ()"><code class="function">g_cond_clear()</code></a> when done.
</p>
<p>
A <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> should only be accessed via the <code class="function">g_cond_</code>
functions.
</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-init"></a><h3>g_cond_init ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_init                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
Initialises a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> so that it can be used.
</p>
<p>
This function is useful to initialise a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> that has been
allocated as part of a larger structure.  It is not necessary to
initialise a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> that has been statically allocated.
</p>
<p>
To undo the effect of <a class="link" href="glib-Threads.html#g-cond-init" title="g_cond_init ()"><code class="function">g_cond_init()</code></a> when a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> is no longer
needed, use <a class="link" href="glib-Threads.html#g-cond-clear" title="g_cond_clear ()"><code class="function">g_cond_clear()</code></a>.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-cond-init" title="g_cond_init ()"><code class="function">g_cond_init()</code></a> on an already-initialised <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> leads
to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>an uninitialized <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-clear"></a><h3>g_cond_clear ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_clear                        (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
Frees the resources allocated to a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> with <a class="link" href="glib-Threads.html#g-cond-init" title="g_cond_init ()"><code class="function">g_cond_init()</code></a>.
</p>
<p>
This function should not be used with a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> that has been
statically allocated.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-cond-clear" title="g_cond_clear ()"><code class="function">g_cond_clear()</code></a> for a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> on which threads are
blocking leads to undefined behaviour.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>an initialised <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-wait"></a><h3>g_cond_wait ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_wait                         (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>);</pre>
<p>
Atomically releases <em class="parameter"><code>mutex</code></em> and waits until <em class="parameter"><code>cond</code></em> is signalled.
</p>
<p>
When using condition variables, it is possible that a spurious wakeup
may occur (ie: <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> returns even though <a class="link" href="glib-Threads.html#g-cond-signal" title="g_cond_signal ()"><code class="function">g_cond_signal()</code></a> was
not called).  It's also possible that a stolen wakeup may occur.
This is when <a class="link" href="glib-Threads.html#g-cond-signal" title="g_cond_signal ()"><code class="function">g_cond_signal()</code></a> is called, but another thread acquires
<em class="parameter"><code>mutex</code></em> before this thread and modifies the state of the program in
such a way that when <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> is able to return, the expected
condition is no longer met.
</p>
<p>
For this reason, <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> must always be used in a loop.  See
the documentation for <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> for a complete example.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> that is currently locked</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-timed-wait"></a><h3>g_cond_timed_wait ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_cond_timed_wait                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *abs_time</code></em>);</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">g_cond_timed_wait</code> has been deprecated since version 2.32 and should not be used in newly-written code. Use <a class="link" href="glib-Threads.html#g-cond-wait-until" title="g_cond_wait_until ()"><code class="function">g_cond_wait_until()</code></a> instead.</p>
</div>
<p>
Waits until this thread is woken up on <em class="parameter"><code>cond</code></em>, but not longer than
until the time specified by <em class="parameter"><code>abs_time</code></em>. The <em class="parameter"><code>mutex</code></em> is unlocked before
falling asleep and locked again before resuming.
</p>
<p>
If <em class="parameter"><code>abs_time</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, <a class="link" href="glib-Threads.html#g-cond-timed-wait" title="g_cond_timed_wait ()"><code class="function">g_cond_timed_wait()</code></a> acts like <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a>.
</p>
<p>
This function can be used even if <a class="link" href="glib-Deprecated-Thread-APIs.html#g-thread-init" title="g_thread_init ()"><code class="function">g_thread_init()</code></a> has not yet been
called, and, in that case, will immediately return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>.
</p>
<p>
To easily calculate <em class="parameter"><code>abs_time</code></em> a combination of <a class="link" href="glib-Date-and-Time-Functions.html#g-get-current-time" title="g_get_current_time ()"><code class="function">g_get_current_time()</code></a>
and <a class="link" href="glib-Date-and-Time-Functions.html#g-time-val-add" title="g_time_val_add ()"><code class="function">g_time_val_add()</code></a> can be used.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> that is currently locked</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>abs_time</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a>, determining the final time</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cond</code></em> was signalled, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> on timeout</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-wait-until"></a><h3>g_cond_wait_until ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_cond_wait_until                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> *mutex</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint64" title="gint64"><span class="type">gint64</span></a> end_time</code></em>);</pre>
<p>
Waits until either <em class="parameter"><code>cond</code></em> is signalled or <em class="parameter"><code>end_time</code></em> has passed.
</p>
<p>
As with <a class="link" href="glib-Threads.html#g-cond-wait" title="g_cond_wait ()"><code class="function">g_cond_wait()</code></a> it is possible that a spurious or stolen wakeup
could occur.  For that reason, waiting on a condition variable should
always be in a loop, based on an explicitly-checked predicate.
</p>
<p>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> is returned if the condition variable was signalled (or in the
case of a spurious wakeup).  <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> is returned if <em class="parameter"><code>end_time</code></em> has
passed.
</p>
<p>
The following code shows how to correctly perform a timed wait on a
condition variable (extended the example presented in the
documentation for <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>):
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
gpointer
pop_data_timed (void)
{
  gint64 end_time;
  gpointer data;

  g_mutex_lock (&amp;data_mutex);

  end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
  while (!current_data)
    if (!g_cond_wait_until (&amp;data_cond, &amp;data_mutex, end_time))
      {
        // timeout has passed.
        g_mutex_unlock (&amp;data_mutex);
        return NULL;
      }

  // there is data for us
  data = current_data;
  current_data = NULL;

  g_mutex_unlock (&amp;data_mutex);

  return data;
}
</pre></div>
<p>
</p>
<p>
Notice that the end time is calculated once, before entering the
loop and reused.  This is the motivation behind the use of absolute
time on this API -- if a relative time of 5 seconds were passed
directly to the call and a spurious wakeup occurred, the program would
have to start over waiting again (which would lead to a total wait
time of more than 5 seconds).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mutex</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GMutex" title="union GMutex"><span class="type">GMutex</span></a> that is currently locked</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>end_time</code></em> :</span></p></td>
<td>the monotonic time to wait until</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on a signal, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> on a timeout</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-signal"></a><h3>g_cond_signal ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_signal                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
If threads are waiting for <em class="parameter"><code>cond</code></em>, at least one of them is unblocked.
If no threads are waiting for <em class="parameter"><code>cond</code></em>, this function has no effect.
It is good practice to hold the same lock as the waiting thread
while calling this function, though not required.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-cond-broadcast"></a><h3>g_cond_broadcast ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_cond_broadcast                    (<em class="parameter"><code><a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a> *cond</code></em>);</pre>
<p>
If threads are waiting for <em class="parameter"><code>cond</code></em>, all of them are unblocked.
If no threads are waiting for <em class="parameter"><code>cond</code></em>, this function has no effect.
It is good practice to lock the same mutex as the waiting threads
while calling this function, though not required.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>cond</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GCond" title="struct GCond"><span class="type">GCond</span></a>
</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GPrivate"></a><h3>struct GPrivate</h3>
<pre class="programlisting">struct GPrivate {
};
</pre>
<p>
The <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> struct is an opaque data structure to represent a
thread-local data key. It is approximately equivalent to the
<code class="function">pthread_setspecific()</code>/<code class="function">pthread_getspecific()</code> APIs on POSIX and to
<code class="function">TlsSetValue()</code>/<code class="function">TlsGetValue()</code> on Windows.
</p>
<p>
If you don't already know why you might want this functionality,
then you probably don't need it.
</p>
<p>
<a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> is a very limited resource (as far as 128 per program,
shared between all libraries). It is also not possible to destroy a
<a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> after it has been used. As such, it is only ever acceptable
to use <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> in static scope, and even then sparingly so.
</p>
<p>
See <a class="link" href="glib-Threads.html#G-PRIVATE-INIT:CAPS" title="G_PRIVATE_INIT()"><code class="function">G_PRIVATE_INIT()</code></a> for a couple of examples.
</p>
<p>
The <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> structure should be considered opaque.  It should only
be accessed via the <code class="function">g_private_</code> functions.
</p>
</div>
<hr>
<div class="refsect2">
<a name="G-PRIVATE-INIT:CAPS"></a><h3>G_PRIVATE_INIT()</h3>
<pre class="programlisting">#define G_PRIVATE_INIT(notify)
</pre>
<p>
A macro to assist with the static initialisation of a <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a>.
</p>
<p>
This macro is useful for the case that a <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function
should be associated the key.  This is needed when the key will be
used to point at memory that should be deallocated when the thread
exits.
</p>
<p>
Additionally, the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> will also be called on the previous
value stored in the key when <a class="link" href="glib-Threads.html#g-private-replace" title="g_private_replace ()"><code class="function">g_private_replace()</code></a> is used.
</p>
<p>
If no <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> is needed, then use of this macro is not
required -- if the <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> is declared in static scope then it will
be properly initialised by default (ie: to all zeros).  See the
examples below.
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
static GPrivate name_key = G_PRIVATE_INIT (g_free);

// return value should not be freed
const gchar *
get_local_name (void)
{
  return g_private_get (&amp;name_key);
}

void
set_local_name (const gchar *name)
{
  g_private_replace (&amp;name_key, g_strdup (name));
}


static GPrivate count_key;   // no free function

gint
get_local_count (void)
{
  return GPOINTER_TO_INT (g_private_get (&amp;count_key));
}

void
set_local_count (gint count)
{
  g_private_set (&amp;count_key, GINT_TO_POINTER (count));
}
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a>
</td>
</tr></tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="g-private-get"></a><h3>g_private_get ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_private_get                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> *key</code></em>);</pre>
<p>
Returns the current value of the thread local variable <em class="parameter"><code>key</code></em>.
</p>
<p>
If the value has not yet been set in this thread, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
Values are never copied between threads (when a new thread is
created, for example).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the thread-local value</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-private-set"></a><h3>g_private_set ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_private_set                       (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> *key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);</pre>
<p>
Sets the thread local variable <em class="parameter"><code>key</code></em> to have the value <em class="parameter"><code>value</code></em> in the
current thread.
</p>
<p>
This function differs from <a class="link" href="glib-Threads.html#g-private-replace" title="g_private_replace ()"><code class="function">g_private_replace()</code></a> in the following way:
the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>key</code></em> is not called on the old value.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
<td>the new value</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-private-replace"></a><h3>g_private_replace ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_private_replace                   (<em class="parameter"><code><a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a> *key</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);</pre>
<p>
Sets the thread local variable <em class="parameter"><code>key</code></em> to have the value <em class="parameter"><code>value</code></em> in the
current thread.
</p>
<p>
This function differs from <a class="link" href="glib-Threads.html#g-private-set" title="g_private_set ()"><code class="function">g_private_set()</code></a> in the following way: if
the previous value was non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> then the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> handler for
<em class="parameter"><code>key</code></em> is run on it.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GPrivate" title="struct GPrivate"><span class="type">GPrivate</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
<td>the new value</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.32</p>
</div>
<hr>
<div class="refsect2">
<a name="GOnce"></a><h3>struct GOnce</h3>
<pre class="programlisting">struct GOnce {
  volatile GOnceStatus status;
  volatile gpointer retval;
};
</pre>
<p>
A <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct controls a one-time initialization function. Any
one-time initialization function must have its own unique <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
struct.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term">volatile <a class="link" href="glib-Threads.html#GOnceStatus" title="enum GOnceStatus"><span class="type">GOnceStatus</span></a> <em class="structfield"><code><a name="GOnce.status"></a>status</code></em>;</span></p></td>
<td>the status of the <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
</td>
</tr>
<tr>
<td><p><span class="term">volatile <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> <em class="structfield"><code><a name="GOnce.retval"></a>retval</code></em>;</span></p></td>
<td>the value returned by the call to the function, if <em class="parameter"><code>status</code></em>
is <a class="link" href="glib-Threads.html#G-ONCE-STATUS-READY:CAPS"><code class="literal">G_ONCE_STATUS_READY</code></a>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="GOnceStatus"></a><h3>enum GOnceStatus</h3>
<pre class="programlisting">typedef enum {
  G_ONCE_STATUS_NOTCALLED,
  G_ONCE_STATUS_PROGRESS,
  G_ONCE_STATUS_READY
} GOnceStatus;
</pre>
<p>
The possible statuses of a one-time initialization function
controlled by a <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="G-ONCE-STATUS-NOTCALLED:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_NOTCALLED</code></span></p></td>
<td>the function has not been called yet.
</td>
</tr>
<tr>
<td><p><a name="G-ONCE-STATUS-PROGRESS:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_PROGRESS</code></span></p></td>
<td>the function call is currently in progress.
</td>
</tr>
<tr>
<td><p><a name="G-ONCE-STATUS-READY:CAPS"></a><span class="term"><code class="literal">G_ONCE_STATUS_READY</code></span></p></td>
<td>the function has been called.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="G-ONCE-INIT:CAPS"></a><h3>G_ONCE_INIT</h3>
<pre class="programlisting">#define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }
</pre>
<p>
A <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> must be initialized with this macro before it can be used.
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
  GOnce my_once = G_ONCE_INIT;
</pre></div>
<p>
</p>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="g-once"></a><h3>g_once()</h3>
<pre class="programlisting">#define             g_once(once, func, arg)</pre>
<p>
The first call to this routine by a process with a given <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a>
struct calls <em class="parameter"><code>func</code></em> with the given argument. Thereafter, subsequent
calls to <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a>  with the same <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct do not call <em class="parameter"><code>func</code></em>
again, but return the stored result of the first call. On return
from <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a>, the status of <em class="parameter"><code>once</code></em> will be <a class="link" href="glib-Threads.html#G-ONCE-STATUS-READY:CAPS"><code class="literal">G_ONCE_STATUS_READY</code></a>.
</p>
<p>
For example, a mutex or a thread-specific data key must be created
exactly once. In a threaded environment, calling <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a> ensures
that the initialization is serialized across multiple threads.
</p>
<p>
Calling <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a> recursively on the same <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct in
<em class="parameter"><code>func</code></em> will lead to a deadlock.
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
  gpointer
  get_debug_flags (void)
  {
    static GOnce my_once = G_ONCE_INIT;

    g_once (&amp;my_once, parse_debug_flags, NULL);

    return my_once.retval;
  }
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>once</code></em> :</span></p></td>
<td>a <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> structure</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
<td>the <a class="link" href="glib-Threads.html#GThreadFunc" title="GThreadFunc ()"><span class="type">GThreadFunc</span></a> function associated to <em class="parameter"><code>once</code></em>. This function
is called only once, regardless of the number of times it and
its associated <a class="link" href="glib-Threads.html#GOnce" title="struct GOnce"><span class="type">GOnce</span></a> struct are passed to <a class="link" href="glib-Threads.html#g-once" title="g_once()"><code class="function">g_once()</code></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>arg</code></em> :</span></p></td>
<td>data to be passed to <em class="parameter"><code>func</code></em>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="g-once-init-enter"></a><h3>g_once_init_enter ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_once_init_enter                   (<em class="parameter"><code>volatile <span class="type">void</span> *location</code></em>);</pre>
<p>
Function to be called when starting a critical initialization
section. The argument <em class="parameter"><code>location</code></em> must point to a static
0-initialized variable that will be set to a value other than 0 at
the end of the initialization section. In combination with
<a class="link" href="glib-Threads.html#g-once-init-leave" title="g_once_init_leave ()"><code class="function">g_once_init_leave()</code></a> and the unique address <em class="parameter"><code>value_location</code></em>, it can
be ensured that an initialization section will be executed only once
during a program's life time, and that concurrent threads are
blocked until initialization completed. To be used in constructs
like this:
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
  static gsize initialization_value = 0;

  if (g_once_init_enter (&amp;initialization_value))
    {
      gsize setup_value = 42; /** initialization code here **/

      g_once_init_leave (&amp;initialization_value, setup_value);
    }

  /** use initialization_value here **/
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>location</code></em> :</span></p></td>
<td>location of a static initializable variable containing 0</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the initialization section should be entered,
<a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> and blocks otherwise</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.14</p>
</div>
<hr>
<div class="refsect2">
<a name="g-once-init-leave"></a><h3>g_once_init_leave ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_once_init_leave                   (<em class="parameter"><code>volatile <span class="type">void</span> *location</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> result</code></em>);</pre>
<p>
Counterpart to <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a>. Expects a location of a static
0-initialized initialization variable, and an initialization value
other than 0. Sets the variable to the initialization value, and
releases concurrent threads blocking in <a class="link" href="glib-Threads.html#g-once-init-enter" title="g_once_init_enter ()"><code class="function">g_once_init_enter()</code></a> on this
initialization variable.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>location</code></em> :</span></p></td>
<td>location of a static initializable variable containing 0</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>result</code></em> :</span></p></td>
<td>new non-0 value for *<em class="parameter"><code>value_location</code></em>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.14</p>
</div>
<hr>
<div class="refsect2">
<a name="g-bit-lock"></a><h3>g_bit_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_bit_lock                          (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>.  If the bit is already
set, this call will block until <a class="link" href="glib-Threads.html#g-bit-unlock" title="g_bit_unlock ()"><code class="function">g_bit_unlock()</code></a> unsets the
corresponding bit.
</p>
<p>
Attempting to lock on two different bits within the same integer is
not supported and will very probably cause deadlocks.
</p>
<p>
The value of the bit that is set is (1u &lt;&lt; <em class="parameter"><code>bit</code></em>).  If <em class="parameter"><code>bit</code></em> is not
between 0 and 31 then the result is undefined.
</p>
<p>
This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to an integer</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.24</p>
</div>
<hr>
<div class="refsect2">
<a name="g-bit-trylock"></a><h3>g_bit_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_bit_trylock                       (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>, returning <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if
successful.  If the bit is already set, returns <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> immediately.
</p>
<p>
Attempting to lock on two different bits within the same integer is
not supported.
</p>
<p>
The value of the bit that is set is (1u &lt;&lt; <em class="parameter"><code>bit</code></em>).  If <em class="parameter"><code>bit</code></em> is not
between 0 and 31 then the result is undefined.
</p>
<p>
This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to an integer</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the lock was acquired</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.24</p>
</div>
<hr>
<div class="refsect2">
<a name="g-bit-unlock"></a><h3>g_bit_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_bit_unlock                        (<em class="parameter"><code>volatile <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
Clears the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>.  If another thread is
currently blocked in <a class="link" href="glib-Threads.html#g-bit-lock" title="g_bit_lock ()"><code class="function">g_bit_lock()</code></a> on this same bit then it will be
woken up.
</p>
<p>
This function accesses <em class="parameter"><code>address</code></em> atomically.  All other accesses to
<em class="parameter"><code>address</code></em> must be atomic in order for this function to work
reliably.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to an integer</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.24</p>
</div>
<hr>
<div class="refsect2">
<a name="g-pointer-bit-lock"></a><h3>g_pointer_bit_lock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_pointer_bit_lock                  (<em class="parameter"><code>volatile <span class="type">void</span> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
This is equivalent to g_bit_lock, but working on pointers (or other
pointer-sized values).
</p>
<p>
For portability reasons, you may only lock on the bottom 32 bits of
the pointer.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to a <span class="type">gpointer-sized</span> value</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.30</p>
</div>
<hr>
<div class="refsect2">
<a name="g-pointer-bit-trylock"></a><h3>g_pointer_bit_trylock ()</h3>
<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_pointer_bit_trylock               (<em class="parameter"><code>volatile <span class="type">void</span> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
This is equivalent to g_bit_trylock, but working on pointers (or
other pointer-sized values).
</p>
<p>
For portability reasons, you may only lock on the bottom 32 bits of
the pointer.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to a <span class="type">gpointer-sized</span> value</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>
<a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the lock was acquired</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.30</p>
</div>
<hr>
<div class="refsect2">
<a name="g-pointer-bit-unlock"></a><h3>g_pointer_bit_unlock ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                g_pointer_bit_unlock                (<em class="parameter"><code>volatile <span class="type">void</span> *address</code></em>,
                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> lock_bit</code></em>);</pre>
<p>
This is equivalent to g_bit_unlock, but working on pointers (or other
pointer-sized values).
</p>
<p>
For portability reasons, you may only lock on the bottom 32 bits of
the pointer.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>address</code></em> :</span></p></td>
<td>a pointer to a <span class="type">gpointer-sized</span> value</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>lock_bit</code></em> :</span></p></td>
<td>a bit value between 0 and 31</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.30</p>
</div>
</div>
<div class="refsect1">
<a name="glib-Threads.see-also"></a><h2>See Also</h2>
<a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>, <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.18</div>
</body>
</html>